Embedding API Methods

Get familiar with the API methods for embedding Visier in other applications.

To use the embedding API, run the embedding script on the page in which you want to embed Visier. The script downloads Visier's SDK and makes Visier's embedding APIs available through a visier function. For more information, see Embed the Full Visier Application.

The following table describes the methods you can use with the visier function.

Method

Description

bootstrap(visierConfig, fCallback)

Sets up the application for subsequent requests and passes back the SDK instance once loaded.

bootstrapSession

Authenticates and creates a session if it hasn't already been done. Alternatively, set startSession: true in the visierConfig to create a session in the bootstrap call.

embedApp(sIframeId, sUrl)

Kicks off the embedded application workflow.

  • sIframeId: The ID of the iframe to load the app.
  • sUrl: The starting navigation URL. Optional.

embedCharts(aChartConfigs)

Kicks off the embedded visualization workflow.

  • aChartConfigs: A list of chart configurations corresponding to each visualization to embed.

on(sEventType, fCallback)

Listens for a specific event.

  • sEventType: The event string name.
  • fCallback: A function to trigger on the event.

off(sEventType, fCallback)

Removes event listeners for an event.

  • sEventType: The event string name. Optional. Calling with no parameters clears all events of all types.
  • fCallback: A function to trigger on the event. Optional. Calling without callback removes all handlers to that event.

trigger(sEventType, ...data)

Triggers an event of a specific type.

  • sEventType: The event string name. This is often a Visier-specific workflow trigger such as NAVIGATE.
  • ..data: Any data to be passed to the listener callbacks.

get(sResource): Promise<any>

Gets a resource from Visier, returned as a promise. The only valid resource is APPLICATION_SECTIONS.

destroy()

Cleans up the internal memory of the SDK.

After adding the embedding script to your page, you can add your business logic to embed Visier.

Example: Load the embedded Visier application

Copy 
visier('bootstrap', visierConfig, async function(app) {
    // Request available Visier rooms (application sections) to navigate to
    const sections = await app.get('APPLICATION_SECTIONS');
    // ... Add sections to partner UI
    // Pick starting point to embed Visier
    const startUrl = sections[0].availableRooms[0].roomUrl;
    app.embedApp('id-of-app-iframe-or-container', startUrl);
    // API will use visierConfig to authenticate and load application to iframe
    // Listen for successful loading of app
    app.on(app.eventType.session, (msg) => {
        switch (msg?.code) {
            case 'VISIER_APP_LOADED':
                // App is loaded and ready to be viewed
                break;
        }
    });
    // Listen for errors
    app.on(app.eventType.error, (msg) => {
        switch (msg?.code) {
            case 'AUTO_LOGIN_FAILED':
                // Handle login failure
                break;
        }
    });
});

In the above example, we call the function visier, which is the name supplied in the parameters of the embedding script). We pass visier the following parameters:

visier('bootstrap', visierConfig, async function(app) {

  • bootstrap: The initialize method. It takes in the configuration provided to be used for subsequent events.
  • visierConfig: Your configuration in the embedding script.
  • async function(app) {: A callback function after bootstrap is complete. It passes back an instance of VisierEmbeddedApp, which you can use to make subsequent calls.

const sections = await app.get('APPLICATION_SECTIONS');

  • get: Returns a promise for the specified APPLICATION_SECTIONS request. After this request is returned, you can use the returned information for navigation and to point the application to the landing room.

app.embedApp('id-of-app-iframe-or-container', startUrl);

  • Passes in the iframe's ID (the container that holds the iframe) to embed Viser.
  • Passes in the URL to start the embedded experience.

Example: Navigate to a Visier room

Copy 
visier('bootstrap', visierConfig, async function(app) {
    // Request available Visier rooms (application sections) to navigate to
    const sections = await app.get('APPLICATION_SECTIONS');
    // ...

    app.trigger('NAVIGATE', roomUrl);
});

// or
visier('trigger', 'NAVIGATE', roomUrl);

Example: Embed a Visier visualization

Copy 
visier('bootstrap', visierConfig, async function(app) {
    // Embed two visuals in specific divs on the page
    app.embedCharts([
        {
            contentId: "bbfdf21b-1f37-4504-8397-ac97043555f1",
            containerId: "chart-container-1"
        }, {
            contentId: "b16a1ac4-3b92-47e9-b22b-3bf00d2fa829",
            containerId: "chart-container-2"
        }
    ]);
    // Listen for successful loading of app
    app.on(app.eventType.info, (msg) => {
        switch (msg?.code) {
            case 'EMBEDDED_CHART_RENDERED':
                // A visual has been loaded
                const containerId = msg.source;
                break;
        }
    });
    // Listen for errors
    app.on(app.eventType.error, (msg) => {
        switch (msg?.code) {
            case 'AUTO_LOGIN_FAILED':
                // Handle login failure
                break;
        }
    });
});